# -*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

from traits.api import (Interface, Str, List, Enum, Python,
                        Unicode, Bool)

class IDataFormat(Interface):
  """
  Describe a data format.
  This class describe only file format.
  How this format is read/written is defined in IDataReader/IDataWriter classes
  How this format is internally handled (in memory) is defined in IDataRepr class
  
  This class provides following attributes.
  
  name: IDataFormat format name (ex: OpenDocument Text)
  exts : common file extensions (lower case) (ex: odt)
  ext: default extension, this is an arbitrary choice (ex: odt)
  documentation : how file format is documented (ex: free-specifications)
  restrictions : restrictions about use of this format (ex: open)
  """
  name = Str
  exts = List
  ext = Str

  """ filename pattern.
  Pattern uses Jinja syntax : '{{basename}}.{{ext}}'
  This pattern can be used for almost all file types except those with mandatory
  prefixes.
  {{ext}} : one of extension in 'exts' list
  {{basename}} : filename without extension <=> prefix
  {{num}} : an integer number
  """
  pattern = Str

  """
  How file format is documented.
  Ex: 
    OpenDocument format: free-specifications
    Microsoft Publisher format: undocumented
  """
  documentation = Enum(('free-spec'
                        'restricted-spec',
                        'documentation',
                        'undocumented',
                        'unknown')
                        )

  """
  Software patent problems are not defined here because
  it depends on countries, international conventions and is
  often FUD or potentially not valid !
  For example, in European Union, 
  Software Patents are ILLEGALS
  """
  restrictions = Enum(('open',
                       'restricted',
                       'unknown'
                       ))

  identifier = Str
  alias = Str
  example_text = Unicode
  example_file = Unicode
  binary = Bool
  encoding = Python


